Welcome to the MacOS Instrumentation System SDK release 1.0.6
Common questions-and-answers about instrumentation:
• What is instrumentation?
Instrumentation is code that is put into your software in order to produce data at runtime. Examining this data can help you learn more about your program's behavior. You can use this SDK to produce and examine various types of instrumentation data.
• Specifically?
The most common form of instrumentation data is the trace point. A trace point is just a timestamped event. You can define as many different events as you want. Usually, events correspond to function calls.
The other type of data is statistics — mainly counters and histograms.
• How do I use it?
Your software defines and produces the data by calling the Instrumentation Library; the Instrumentation System records it, and the Instrumentation Viewer application displays it.
Instrumentation data is displayed in a time-based format inside user-configured viewer documents. It can also be exported as text for further analysis by other programs.
The most common reason to use instrumentation is to discover where your code is spending its time.
• How do I put instrumentation into my programs?
There is an API to the instrumentation library, including a set of C macros. The most straight-forward way to instrument your program is to add calls that define and produce instrumentation data to your source code.
You can also use the MrPlus tool to add trace instrumentation to your executable without changing your source code. See the “Instrumentation System User’s Guide” for details.
• Where can it go?
Most instrumentation can be defined and produced from any executable — application, driver, MPW tool, what-have-you — at any time, including interrupt time.
• Is it expensive?
Effort has been made to keep the production end of instrumentation light-weight. On a 100MHz 601, logging a trace to an instrumentation point that is in-cache requires 3-4 microseconds; 10-12 microseconds if L2 or TLB cache misses are encountered. Updating other instrumentation has similar costs.
• Do the costs show up in the timings?
No attempt has been made to “factor out” the overhead associated with instrumentation, because the times are absolute times that relate to other events in the system rather than just time differences. Dealing with this is a problem that is under investigation.
In the meantime, the hope is that instrumentation overhead is not a significant part of the runtime, or that where it is it may be discounted “manually.”
• Is it PowerPC-only?
The Instrumentation System will not run on 68K-based Macintoshes. However, 68K code running on a PowerPC-based machine can produce instrumentation data by statically linking against the 68K instrumentation library. The library operates by calling the PowerPC implementation through the Mixed Mode Manager.
• Once I've installed the Instrumentation System, how do I tell if it's working correctly?
1) Launch the InstTest application in the Test Target folder. This will log trace points.
2) Run the OneShot Collector application in the “Instrumentation ƒ” to produce the “Instrumentation Data” file.
3) Double-click the "InstTest view" document inside the Viewer files folder to launch the Instrumentation Viewer.
4) Open the “Instrumentation Data” file inside “Instrumentation ƒ” using the File menu.
This should show you trace data produced by the InstTest application.
(If you launched the Instrumentation Viewer directly, you should ensure that you are in Browse mode. See the Instrumentation Viewer User’s Guide for details.)
• Where do I turn for support?
The first step is to read all of the documentation. (See below.)
If you have further questions, you can post them to the MPW-DEV Internet mailing list. You can get subscription information about this mailing list at <http://www.solutions.apple.com/ListAdmin/>, or send mail to info@solutions.apple.com.
Documentation
This distribution includes the following documentation:
The Instrumentation System User’s Guide. This introduces the Instrumentation System and describes how to install and use it to collect instrumentation data.
The Instrumentation Programmer’s Guide. This describes the client API that is used to provide data to the Instrumentation System.
Sample Code. This consists of several short snippets illustrating how to define and log instrumentation data.
The Instrumentation Viewer User’s Guide. This describes the Instrumentation Viewer, the primary tool for displaying and analyzing instrumentation data.
What's new in 1.0.6
- This is a minor bugfix / feature update. The following changes were made:
2241683 - The setting for the “Trace data buffer size” is no longer being ignored, so you can collect more than the last 32K of user-defined trace data.
1647124 - You can now open the data files by double-clicking on them in the Finder. (You may have to rebuild your desktop.) In addition, the Viewer now warns you when you open an empty data file.
The SpoolPackager now always looks for spool data files in the “Instrumentation ƒ” folder and places the Instrumentation Data file there.
This release contains the instrumented InterfaceLib that first appeared on E.T.O. 22. See the ReadMe in the “Experimental InterfaceLib” folder for more details.
What's new in 1.0.5
- This release contains bug fixes in the Instrumentation Viewer. The Instrumentation System User’s Guide and Instrumentation Programmer's Guide have also been slightly modified. The following bugs were fixed:
1400835 - The Instrumentation tree window could be overwritten with viewer pane scrollbars on switching from layout to browser mode.
1616972 - If a multi-part event is logged and the instrumentation data does not contain an end event, the event range duration appears to be an impossibly huge number.
1635134 - The minimum heights for some viewers are too small, causing things like scroll bar thumb overwriting of scroll arrows, etc.
1634541 - The current time text just to the left of the time slider left truncates more than necessary.
What's new in 1.0.4
- This release contains a bug fix release of Instrumentation Viewer. Also, the viewer documentation, Instrumentation Viewer User’s Guide, has been updated to match the current feature set of the viewer. The InstrumentationBackend library, used by the viewer, has also been updated. The following bugs were fixed.
1616981 - Inst. Viewer crashes after setting the "View Data from" popup for a view to "Comparison File", which is "NULL", and then switching to Browse mode.
1613279 - When live data is present and the user opens the Live Data window, the enable/disable column does not accurately reflect the real state of the nodes. It should at least scan through the list when it is opened and mark disabled nodes as disabled.
1619727 - When viewing data live with Instrumentation Viewer, if you change the enable/disable state, then close and reopen the live connection window, the changes are not reflected in the reopened window.
1622392 - Some of the viewers have no text in their viewer options pallette "Viewer Information" display.
1616837 - The names of the viewers should be more consistent. Most names follow the form
<Inst Type> <View Type> Viewer. A few follow the form <View Type> <Inst Type> Viewer.
1616846 - The order of viewers in the Viewer Pallette should be such that the trace viewers are separated from the statistics viewers. Currently, the trace viewers fall in-between various statistics viewers. The trace viewers should probably appear at the top, since the documents tend to address traces before statistics and traces are probably more commonly used than statistics.
1620577 - Small cosmetic problem: the viewer doc window vertical scroll bar is 1 pixel too narrow.
What's new in 1.0.3
- This release includes an experimental InterfaceLib that logs start/end trace events across its exported routines. In order to use it, place it and the ProfileLib.3 library in the same folder as your application, and launch your application. It should produce a trace record for every cross-TOC call to InterfaceLib.
This, coupled with the Instrumentation Viewer's Trace Ranking Summary, is an easy way to obtain a general profile of an application's OS usage. (You can use the instrumented InterfaceLib with non-application code fragments as well.)
This particular InterfaceLib has run successfully with MPW 3.4.2b3, and with the Tempo Finder running on Harmony b5c3.
(The following InterfaceLib routines were not instrumented, due to limitations in MrPlus: DebugStr, Debugger, c2pstr, p2cstr, NBPSetNTE, and the BlockMove/BlockZero family.)
- A small window in which access to the instrumentation tree could be improperly synchronized at interrupt time or under MP has been closed. (1600600)
- Some bugs involving clients trying to create trace classes and log traces while the instrumentation library is being initialized have been fixed.
What's new in 1.0.2
- InstLogTraceEventWithData() and InstLogTraceEventWithDataStructure(), which are used to log traces containing user-defined data, can now be called at interrupt time. (1600595)
What's new in 1.0.1
- Missing trace counts are no longer inflated by previous runs of the OneShot Collector. (1402430)
- Calling InstInitialize68K() inside the MPW InstrumentationLib68K.o library now works correctly.
- Remember that if you are updating from 1.0b8 or earlier, you must convert your code to use the renamed identifiers in Instrumentation.h. See the "Interface Thrash" folder for details.
